The Decorations API was introduced to Visual Studio Code as a way to decorate pieces of code. It allows you to grab ranges of text in an editor and decorate it using a subset of CSS properties. It does not modify the code but rather gives a visual addition in VS Code to how you can interpret your code.

As well, in VS Code 1.3, they added support to use the ::before and ::after pseudoelements on these decorations through the API which is commonly seen in various extensions now in 2018.

Decorations has been widely adopted across the extension community and here are a sample of extensions that show off what can be done with decorations:

Supercharge the Git capabilities built into Visual Studio Code — Visualize code authorship at a glance via Git blame annotations and code lens, seamlessly navigate and explore Git repositories, gain valuable insights via powerful comparison commands, and so much more

Display import/require package size in the editor

Live Scratchpad for JavaScript.

Python live scratchpad

highlight TODOs, FIXMEs, and any keywords, annotations...

A vscode extension to help visualize css colors in files.

Annotations for parameters in your JS / TS Files to mimic named parameters

Adds color highlighting to log files to make it easier to follow the flow of log events and identify problems.

To show off how to use the decorations, I am going to be writing an example extension that will highlight all locations of console.log in JS files

If you want to download the code to follow along, head over to lannonbr/console-log-highlighter. It was generated with the yeoman vscode generator.

If you open up src/extension.ts, The first piece of code is the decoration type.

This describes how we want to style the decoration. For this example, I am going to just decorate the text itself, but if you are interested, you can add before and after objects to add pseudo elements to the decoration. (GitLens uses this to push the inline blame after the end of the line)

The following things can be styled which map to their respective css properties:

As well, you can insert these into light and dark objects so you can customize how it will appear for specifically light or dark color themes.

Next in the activate function, I have a event listener which will watch for document saves. Any time the file is saved this will be called. I grab the editor open and pass it into a decorate function which will do the heavy lifting on setting the decorations:

Following is the decorate function which takes a vscode.TextEditor as a parameter. First we setup some boilerplate by grabbing the text from the editor, setting up a regex to look for console.log, and as well create an array where the decorations will live.

Next I loop over each line of the code and will try looking for console.log. If I can find it, I create a range for which the decoration will cover. Each decoration requires at least a range which includes a starting and ending position for where the text is. In VS Code internally, line and columns are 0-indexed, so if we had a file have console.log at the beginning of the document, it would start at line 0, col 0.